动机 / Motivation

本 PR 实现了完整的 AstrBot SDK v4 插件系统，旨在解决以下问题：

1. 插件隔离性问题：旧版插件与主进程共享内存，插件崩溃可能导致整个系统不稳定
2. 开发体验问题：旧版插件 API 不够直观，缺乏声明式装饰器和类型提示
3. 能力扩展问题：插件无法方便地调用 LLM、Memory、DB 等核心能力
4. 测试困难问题：旧版插件难以进行单元测试和集成测试

设计原则：旧插件走旧逻辑，新插件走 SDK，保证旧逻辑依旧能使用的情况下写新 SDK 桥接。

改动点 / Modifications

1. 新增 astrbot-sdk 独立包 (约 68,000+ 行代码)

核心模块：

• context.py - 统一的运行时上下文，组合所有能力客户端
• decorators.py - 声明式装饰器系统 (@on_command, @on_message, @require_admin, @rate_limit 等)
• events.py - MessageEvent 事件对象，支持 reply(), send_streaming(), react() 等
• errors.py - 类型化错误系统，支持 docs_url 和 details 扩展
• star.py - Star 基类和生命周期管理

能力客户端 (clients/)：

• llm.py - LLM 聊天、流式聊天、Tool Loop
• memory.py - 记忆存储、搜索、TTL 管理
• db.py - KV 持久化、Watch 订阅
• platform.py - 消息发送、会话管理
• provider.py - Provider 查询、TTS/STT/Embedding
• managers.py - 人格/对话/知识库管理客户端

运行时系统 (runtime/)：

• supervisor.py - Supervisor 运行时，管理多个 Worker 进程
• worker.py - Worker 运行时，处理单个插件进程
• peer.py - 基于 JSON-RPC 的对等通信
• transport.py - 基于 stdio 的传输层
• handler_dispatcher.py - Handler 匹配与分发
• capability_router.py - 能力注册与路由
• loader.py - 插件发现与加载
• environment_groups.py - 环境组管理

协议层 (protocol/)：

• descriptors.py - HandlerDescriptor, CapabilityDescriptor 声明式元数据
• messages.py - 协议消息类型
• _builtin_schemas.py - 内置 JSON Schema

完整文档 (docs/)：

• 12+ MD 文件，涵盖 Context API、事件组件、装饰器、Star 生命周期、客户端、错误处理、高级主题、测试指南、API 参考、迁移指南、安全检查清单

2. 新增核心桥接层 (astrbot/core/sdk_bridge/)

核心组件：

• plugin_bridge.py (约 3000 行) - SDK 插件桥接主类

  • 插件生命周期管理 (reload_all(), turn_on_plugin(), turn_off_plugin())
  • 消息/事件分发 (dispatch_message(), dispatch_system_event())
  • 请求覆盖层管理 (_RequestOverlayState)
  • HTTP API 注册
  • Session Waiter 支持
  • Skill 注册支持

• capability_bridge.py - 核心能力桥接，组合 10+ 个 Mixin：

  • ProviderCapabilityMixin - Provider 查询、TTS/STT/Embedding/Rerank
  • PlatformCapabilityMixin - 平台管理、消息发送
  • KnowledgeBaseCapabilityMixin - 知识库 CRUD、文档管理
  • ConversationCapabilityMixin - 对话管理
  • PersonaCapabilityMixin - 人格管理
  • SessionCapabilityMixin - 会话级插件/服务开关
  • SkillCapabilityMixin - 技能注册
  • LLMCapabilityMixin - LLM 聊天、流式聊天
  • SystemCapabilityMixin - 数据目录、文本转图片、文件令牌
  • BasicCapabilityMixin - DB、Memory、HTTP、Metadata

• event_converter.py - AstrMessageEvent ↔ SDK 事件载荷转换

• trigger_converter.py - Handler 触发器匹配（命令/正则/关键词）

3. 核心模块修改

Pipeline 集成：

• pipeline/process_stage/stage.py - 增加 SDK 分发逻辑
• pipeline/respond/stage.py - 支持 SDK 结果覆盖
• pipeline/result_decorate/stage.py - 兼容 SDK 消息链

Platform 适配：

• platform/sources/discord/discord_platform_adapter.py - 支持 SDK 原生命令菜单
• platform/sources/telegram/tg_adapter.py - 支持 SDK 原生命令菜单

Star 系统兼容：

• star/star_manager.py - 集成 SDK 插件管理
• star/context.py - 添加 SDK 桥接入口

Skills 集成：

• skills/skill_manager.py - 支持 SDK 技能注册 (prune_sdk_plugin_skills, replace_sdk_plugin_skills)

4. Dashboard 集成

• dashboard/routes/command.py - SDK 命令管理（只读）
• dashboard/routes/tools.py - SDK LLM 工具管理
• dashboard/routes/skills.py - SDK 技能管理
• dashboard/src/components/ - 前端组件更新，支持 SDK 命令/工具标识

5. 测试覆盖

SDK 包测试 (astrbot-sdk/tests/)： 24 个测试文件

• 命令匹配、装饰器、Memory 客户端、LLM 工具注册
• Session Waiter、Peer 通信、Supervisor 同步
• Provider 回归测试、加载器回归测试

核心桥接测试 (tests/test_sdk/unit/)： 13 个测试文件

• SDK 桥接基础、运行时能力、Memory 能力
• LLM 能力、消息对象、原生命令注册
• 人格/对话/知识库管理、Provider/平台管理

技术亮点

1. 多进程隔离架构

┌─────────────────────────────────────────────────────────────┐
│                     AstrBot Core (Python)                    │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              SdkPluginBridge                          │   │
│  │  ┌────────────────────────────────────────────────┐  │   │
│  │  │          CoreCapabilityBridge                   │  │   │
│  │  │    (ProviderMixin, PlatformMixin, ...)          │  │   │
│  │  └────────────────────────────────────────────────┘  │   │
│  └──────────────────────────────────────────────────────┘   │
│            │ StdioTransport            │                     │
│            ▼                           ▼                     │
│  ┌─────────────────┐         ┌─────────────────┐            │
│  │  WorkerSession  │         │  WorkerSession  │            │
│  │   (Plugin A)    │         │   (Plugin B)    │            │
│  └─────────────────┘         └─────────────────┘            │
└─────────────────────────────────────────────────────────────┘

• 每个 SDK 插件运行在独立子进程中
• 通过 JSON-RPC over stdio 通信
• 插件崩溃不影响主进程

2. 声明式装饰器系统

from astrbot_sdk import on_command, Context, MessageEvent

@on_command("hello", aliases={"hi", "hey"})
@require_admin
@rate_limit(max_calls=10, window_seconds=60)
async def hello_handler(event: MessageEvent, ctx: Context):
    await event.reply("Hello!")

3. 类型安全的参数注入

• 支持按类型注解注入 MessageEvent, Context
• 支持 Optional[T] 和 T | None 语法
• 支持命令参数解析

4. 请求级状态管理

• _RequestOverlayState 管理 LLM 决策覆盖
• 支持请求级结果缓存
• 支持请求级 extras 传递

5. 流式执行支持

• StreamExecution 包装异步迭代器
• 支持 TTS 流式音频输出
• 支持消息流式发送

文件变更统计

主要新增目录：

• astrbot-sdk/ - 完整的 SDK 包
• astrbot/core/sdk_bridge/ - 核心桥接层
• tests/test_sdk/ - 集成测试

Breaking Changes

• 这不是一个破坏性变更

兼容性保证：

• 旧版 Star 插件继续使用原有机制，不受影响
• 新版 SDK 插件使用新的能力系统
• 两种插件可以共存

验证步骤 / Verification Steps

# 1. 运行 SDK 包测试
cd astrbot-sdk && uv run pytest tests/ -v

# 2. 运行核心桥接测试
uv run pytest tests/test_sdk/ -v

# 3. 启动 AstrBot 并加载 SDK 插件
uv run python main.py

# 4. 验证旧版插件兼容性
# 将旧版插件放入 addons/ 目录，确认正常加载和执行

Checklist / 检查清单

• 😊 新功能已通过 Issue/邮件等方式与作者讨论过
• 👀 代码经过良好测试，已提供验证步骤
• 🤓 新依赖已添加到 astrbot-sdk/pyproject.toml（SDK 包独立依赖）
• 😮 代码无恶意内容

相关 Issue

• SDK v4 架构设计与实现
• 多进程插件隔离
• 声明式 Handler 注册
• 能力系统扩展